OpenCode 中让 MiniMax 两个 MCP 共存：Token Plan + 完整版

MiniMax 官方同时维护着两个用途不同的 MCP 服务：

Token Plan MCP (minimax-coding-plan-mcp)：轻量级，只提供 web_search 和 understand_image 两个工具，专为编码场景设计。
完整版 MCP (minimax-mcp)：多模态全家桶，包含 text_to_audio、voice_clone、music_generation、generate_video、text_to_image 等十几个工具。

很多人会下意识只装其中一个，但其实两个可以共存，互不干扰。本文记录完整的踩坑过程和最终配置。

一、为什么需要共存

两个 MCP 的工具集合完全不重叠：

MCP	工具数	典型用途
Token Plan MCP	2	编码时查资料、看图
完整版 MCP	10+	生成语音 / 音乐 / 视频 / 图片

把它们都装上，AI 助手就能既会搜资料又会做多媒体，不需要切换客户端。

二、官方文档的"坑"

按照 Token Plan MCP 文档和完整版 MCP 文档的说明，理论上只需要这样配置：

{
  "mcp": {
    "MiniMax": {
      "type": "local",
      "command": ["uvx", "minimax-mcp"],
      "environment": {
        "MINIMAX_API_KEY": "<YOUR_API_KEY>",
        "MINIMAX_MCP_BASE_PATH": "C:\\path\\to\\output",
        "MINIMAX_API_HOST": "https://api.minimaxi.com"
      },
      "enabled": true
    }
  }
}

但实际跑起来会立刻报错：

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

三、问题的真正原因

错误信息很迷惑人 —— 包明明装了 mcp，怎么会找不到 mcp.server.fastmcp？

真相是 mcp 库在 2.0 版本做了一次 breaking change，把 FastMCP 类从 mcp.server.fastmcp 移到了 mcp.server.mcpserver。而 minimax-mcp==0.0.4 还在用旧的导入路径 from mcp.server.fastmcp import FastMCP。

uvx 默认会拉取最新版本的 mcp（目前是 2.x），于是启动时立刻崩。

四、解决方案：锁定 mcp<2.0

uvx 支持 --with 参数往隔离环境里注入额外的依赖。我们用它强制装 1.x 版本的 mcp：

uvx --from minimax-mcp --with "mcp>=1.6.0,<2.0.0" minimax-mcp

启动后立刻正常，并且能列出全部 10 个工具。

五、最终配置：两个 MCP 共存

因为 OpenCode 的 mcp 配置里 server name 不能重复（否则冲突），给完整版起一个不同名字（比如 MiniMax-search 给 Token Plan 版）。两个服务可以共享同一个 API Key。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "MiniMax": {
      "type": "local",
      "command": ["uvx", "--from", "minimax-mcp", "--with", "mcp>=1.6.0,<2.0.0", "minimax-mcp"],
      "environment": {
        "MINIMAX_API_KEY": "${MINIMAX_API_KEY}",
        "MINIMAX_API_HOST": "https://api.minimaxi.com",
        "MINIMAX_MCP_BASE_PATH": "C:\\Users\\<YOU>\\MiniMax-mcp-output",
        "MINIMAX_API_RESOURCE_MODE": "local"
      },
      "enabled": true
    },
    "MiniMax-search": {
      "type": "local",
      "command": ["uvx", "--from", "minimax-coding-plan-mcp", "--with", "mcp>=1.6.0,<2.0.0", "minimax-coding-plan-mcp", "-y"],
      "environment": {
        "MINIMAX_API_KEY": "${MINIMAX_API_KEY}",
        "MINIMAX_API_HOST": "https://api.minimaxi.com"
      },
      "enabled": true
    }
  }
}

关键点说明

--with "mcp>=1.6.0,<2.0.0" —— 必须加，否则必报 ModuleNotFoundError。
MINIMAX_MCP_BASE_PATH —— 完整版 MCP 必填，所有生成的多媒体文件都会落盘到这里。提前创建好目录并确保有写权限。
MINIMAX_API_RESOURCE_MODE —— 可选 url（默认，返回 URL）或 local（返回本地路径）。想要文件直接落盘就选 local。
${MINIMAX_API_KEY} —— 用环境变量占位符而不是直接写 API Key。配置里直接写明文 Key 会泄露给任何能读到这个文件的人 / 进程，尤其是同步到 Git 仓库之后。

六、API Key 的安全管理

把 API Key 写进 opencode.json 是个坏习惯，理由很简单：

配置文件可能被截图、上传、误传到公开仓库
同一个 Key 还可能被其他应用复用
Token Plan 的 Key 通常有调用额度，被盗刷会很麻烦

推荐做法：

Windows 上设置用户级环境变量：

[Environment]::SetEnvironmentVariable("MINIMAX_API_KEY", "<YOUR_KEY>", "User")

然后在配置里写 ${MINIMAX_API_KEY}，OpenCode 会自动展开。

或者用 .env 文件 + dotenv，更便携。

七、验证

重启 OpenCode 后输入 /mcp，能看到两个服务都 connected：

✓ MiniMax        connected  (text_to_audio, list_voices, voice_clone, ...)
✓ MiniMax-search connected  (web_search, understand_image)

试着调用一个工具确认无误，例如用 Token Plan 版搜新闻：

调用 MiniMax-search.web_search，查询 今日新闻

或者用完整版生成一张图：

调用 MiniMax.text_to_image，prompt 写你想要的画面

八、故障排查清单

现象	原因	处理
`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`	`mcp>=2.0` 破坏 API	加 `--with "mcp>=1.6.0,<2.0.0"`
`spawn uvx ENOENT`	系统找不到 `uvx`	在 `command` 里写绝对路径，如 `C:\\Users\\<YOU>\\.local\\bin\\uvx.exe`
生成的文件找不到	`MINIMAX_MCP_BASE_PATH` 没写或者目录不存在	创建目录并赋写权限
`PermissionError`	Token Plan Key 没有对应权限	确认订阅里有 Token Plan 席位或积分

九、写在最后

MiniMax 官方目前还没有更新包依赖来适配 mcp>=2.0，所以这个 --with "mcp<2.0.0" 的 workaround 还要持续一段时间。等官方发新版包，可以直接简化为：

"command": ["uvx", "minimax-mcp"]

到时候再来更新本文。